This explicitly does not talk about attribute name scoping and resolution. That is a much bigger topic that I might tackle separately.

I'm also looking at documenting the syntax for every built-in attribute, better incorporating MetaItem. I think this should be done separately since it will likely be a large change.

Finally, I've noted a number of built-in attributes that are not documented that probably should be. I'll try to follow up on those later.

Can someone clarify the distinction of inert/active attributes? I can't find anything in rustc that tracks that. In what way is that difference ever observable by the user?

Can someone clarify the distinction of inert/active attributes? I can't find anything in rustc that tracks that. In what way is that difference ever observable by the user?

An active attribute (a macro attribute, cfg, cfg_attr or derive) transforms its input and disappears in the process.
An inert attribute just sits there and waits for being interpreted (by the compiler, or a tool, or a proc macro).

Thanks for the speedy review!

From a language perspective, it seems like the only scenario where the presence/absence of an attribute matters is for attribute and derive macros, right? I've been doing some tests, and it doesn't seem to match my expectations. Attribute macros see cfg attributes if the cfg predicate passes, the cfg isn't removed. If the cfg predicate fails, then everything is pruned before the proc macro gets a chance to run, so that implies that cfg is processed before proc-macros and it should have been removed when it passed. When does a cfg with a passing predicate get removed? How can one write code such that the removal can be observed?

EDIT: I was wrong here, the order of attributes matters. However, test seems to always be "active". When compiling with or without tests, it appears to be removed.
The docs also mention test being either inert or active, but proc-macros see #[test] regardless of whether or not --test is used. Perhaps test runs after proc-macros? In which case, it seems like an unobservable distinction, irrelevant to the language.

I do see that previously processed attribute macros are removed when you have multiple of them.

I want to be clear if Tool Attributes are always inert. I can't find the code where this removal happens, and I can't find a way to observe it (other than the multiple attribute macro situation).

@ehuss

From a language perspective, it seems like the only scenario where the presence/absence of an attribute matters is for attribute and derive macros, right?

I don't understand what this means.
Presence of inert attributes still matters a lot for the language?

cfg is processed before proc-macros

Generally, yes, but in details it's a mess that needs fixing (individual pieces were implemented in different time by different people without understanding the whole picture and having a common "vision").
I have a couple of PRs in the pipeline that'll hopefully land in March, then we'll be able to document how cfg/cfg_attr works relatively to attribute macros and derives.

Attribute macros see cfg attributes if the cfg predicate passes, the cfg isn't removed.

This is an implementation defect, it causes cfg predicates being evaluated multiple times.
At least the predicate result is the same every time (I think) and cfg application is idempotent.
cfg is effectively a macro and it should behave like macro, with exception of the general "early expansion" aspect which we cannot change.

I want to be clear if Tool Attributes are always inert.

The compiler always treats tool attributes as inert.
Tools of course may do anything with them, or with code in general.

Meta: looks like I'm now assigned, but I cannot merge PRs in this repo.

@petrochenkov Oh; uhmm, just leave a note when you think this is in a good state and someone will merge it. :)

Thanks everyone for taking a look!

@petrochenkov thanks, I think that makes it clearer to me.

I'll follow up with separate PR's for some of the other things noted here.